1 - Introduction

react本身是一个UI库，它没有专门的数据获取模式，虽然说获取数据之后，我们可以使用redux这些状态管理库来处理数据在整个应用的共享，但是这些状态管理库本身对client state管理的好（比如说theme），但是对于数据获取，异步、服务器状态不是很管用。

React 工程中一个非常核心的设计点：数据获取（data fetching）和状态管理（state management）。 我们来系统地解释一下👇

---

🧩 一、React 自身的问题：数据获取的痛点

React 本身是一个UI 库，它不负责数据获取或缓存逻辑。当项目开始复杂化（尤其是涉及接口调用）时，就会暴露出几个典型问题。

假设你直接用 useEffect + fetch + useState 来请求接口：

xxxxxxxxxx
18
1
function UserList() {
2
const [users, setUsers] = useState<User[]>([]);
3
const [loading, setLoading] = useState(true);
4
const [error, setError] = useState<Error | null>(null);
5
​
6
useEffect(() => {
7
 setLoading(true);
8
 fetch('/api/users')
9
   .then((res) => res.json())
10
   .then(setUsers)
11
   .catch(setError)
12
   .finally(() => setLoading(false));
13
}, []);
14
​
15
if (loading) return <p>Loading...</p>;
16
if (error) return <p>Error!</p>;
17
return <UserTable data={users} />;
18
}

看似简单，但一旦项目复杂起来，就会出现以下问题👇：

问题	说明
🔁 重复请求	同一个接口可能在多个组件中都被请求多次
🧠 缓存难管理	要自己管理缓存、过期、刷新等逻辑
🕐 重新请求逻辑繁琐	比如窗口重新聚焦、数据变更后重新加载都要手写
⚡ 全局状态难统一	请求状态（loading、error、data）常常散落在各处
♻️ 刷新与同步困难	用户操作后（如新增、删除）如何让列表自动刷新？

这些都是 React 本身不擅长解决的问题。 于是，就有了 React Query（现在叫 TanStack Query）。

---

🚀 二、React Query 是什么？

React Query 是一个用于 数据获取（server state management） 的库。 它的核心目标是：让你不再手写 useEffect 来获取数据。

一句话总结：

🧠 React Query 让你只关心“数据是什么”，而不用关心“什么时候、怎么获取、怎么缓存”。

---

🎯 三、React Query 解决了哪些问题？

1️⃣ 自动管理请求的状态

你不用再写一堆 loading、error、useEffect。

xxxxxxxxxx
12
1
import { useQuery } from "@tanstack/react-query";
2
​
3
function UserList() {
4
  const { data, isLoading, error } = useQuery({
5
    queryKey: ['users'],
6
    queryFn: () => fetch('/api/users').then(res => res.json()),
7
  });
8
​
9
  if (isLoading) return <p>Loading...</p>;
10
  if (error) return <p>Error!</p>;
11
  return <UserTable data={data} />;
12
}

React Query 自动帮你：

• 追踪 loading、error、success 状态；
• 缓存数据；
• 避免重复请求。

---

2️⃣ 缓存与共享

同一个 queryKey 的数据会自动缓存，跨组件共享。

xxxxxxxxxx
1
1
useQuery({ queryKey: ['users'], queryFn: getUsers });

不论在哪个组件中调用，只要 key 一样，就共享同一份数据缓存。

---

3️⃣ 自动刷新与失效

• 页面重新聚焦时自动重新请求；
• 网络恢复后自动重试；
• 支持手动 invalidateQueries(['users']) 来刷新数据。

例如当你新增了一个用户：

xxxxxxxxxx
3
1
mutation.mutate(newUser, {
2
  onSuccess: () => queryClient.invalidateQueries(['users'])
3
});

➡️ 自动让 UserList 重新获取最新数据！

---

4️⃣ 并行与依赖请求

你可以轻松写出：

• 并行请求（多个 useQuery 同时执行）；
• 依赖请求（上一个请求完成后再发下一个）。

---

5️⃣ SSR、分页、预取

React Query 还支持：

• SSR（服务端渲染）
• 分页、无限滚动
• 数据预取（prefetch）
• 缓存时间控制

这些都大大提升了性能与开发体验。

---

🧱 四、React Query vs 全局状态库（Redux、Zustand）

类型	适合管理的数据	说明
React Query	服务端状态（Server State）	从 API 获取的、可能被服务器更新的数据
Redux / Zustand / Jotai	客户端状态（Client State）	用户登录态、UI 开关、临时表单状态等

📌 一句话记住：

✅ “接口数据”用 React Query， ✅ “本地交互状态”用 Redux/Zustand。

---

🌍 五、React Query 的核心理念

让你的 React 应用 以声明式的方式 处理“数据获取”这件事。

你只需要告诉它：

• 你要的数据是什么（queryKey）；
• 怎么获取它（queryFn）； 剩下的缓存、更新、状态、刷新，全部交给 React Query。

---

✅ 总结

问题	React Query 的解决方式
手动写 useEffect	提供 useQuery 自动处理
重复请求	内置缓存与共享
缺乏状态管理	自动提供 isLoading/error/data
刷新困难	invalidateQueries / 自动刷新机制
性能低	缓存、请求去重、后台刷新

这里出现了client state和server state，之前没有了解过这些概念，这个概念在react中还是蛮重要的。

在 React 应用中，确实存在两种性质完全不同的状态：

👉 Client State（客户端状态） 👉 Server State（服务端状态）

它们看起来都叫 “state”，但本质、生命周期、管理方式完全不同。 我们来一步步拆开讲 👇

---

🧠 一、什么是 Client State（客户端状态）

Client State 指的是在浏览器或 React 应用内部自己管理的数据。 它完全存在于前端，不依赖后端。

✅ 典型例子：

• 当前页面的 UI 状态：是否展开某个 modal、当前 tab 是哪个；
• 表单输入值；
• 本地缓存的 token、用户登录状态；
• 组件之间共享的小数据；
• 临时计算结果（比如筛选条件、分页页码）。

🧩 特点：

特征	说明
💾 存在位置	浏览器内存（React 组件、Context、Redux、Zustand 等）
🔄 更新方式	前端代码直接修改
⏳ 生命周期	跟随页面刷新而清空
🚫 不需要 API	不依赖后端
🧰 管理工具	useState / useReducer / Context / Redux / Zustand / Jotai 等

🧠 举例：

xxxxxxxxxx
2
1
const [isOpen, setIsOpen] = useState(false);
2
const [form, setForm] = useState({ name: '', age: '' });

这些都是典型的 Client State。 前端知道怎么改，后端根本不关心。

---

🌍 二、什么是 Server State（服务端状态）

Server State 是从服务器获取的数据，它存在于后端系统，前端只是读取或缓存它。

✅ 典型例子：

• 从接口获取的用户信息；
• 产品列表；
• 后台返回的报表数据；
• 聊天消息、评论列表、通知等。

🧩 特点：

特征	说明
📡 来源	由服务器提供，通过 API 获取
🧠 管理难度	难（需要处理 loading、error、缓存、同步等）
♻️ 更新方式	必须请求或刷新 API
🔁 数据变化	后端更新后，前端需要重新同步
⚙️ 管理工具	React Query / SWR / Apollo / Relay 等

🧠 举例：

xxxxxxxxxx
4
1
const { data, isLoading } = useQuery({
2
  queryKey: ['users'],
3
  queryFn: () => fetch('/api/users').then(res => res.json())
4
});

这些数据不是前端控制的，而是服务器控制的。 前端只能请求 → 缓存 → 刷新。

---

⚖️ 三、两者的区别总结表

对比项	Client State	Server State
数据来源	浏览器内存、本地逻辑	服务器、数据库
更新方式	前端逻辑直接 setState	通过 API 调用
是否可持久化	否（刷新即丢）	是（保存在后端）
是否可共享	通常只在当前页面内	多用户、多客户端共享
典型工具	useState / Redux / Zustand	React Query / SWR / Apollo
主要难点	结构设计、性能优化	缓存、同步、失效、刷新

---

🚀 四、为什么要区分这两种状态？

在 React 早期（比如 Redux 盛行时代），很多人把两者混在一起用：

• API 请求回来的数据也塞进 Redux；
• 导致 Redux store 既管理 UI 状态又管理接口数据；
• 造成复杂、臃肿、重复请求。

后来社区逐渐达成共识：

🧭 Client State → 由前端状态库管理 🧭 Server State → 交给 React Query / SWR 等库管理

这样职责清晰、逻辑更简单。

---

🔧 五、一个直观的对比例子

假设你有一个「用户列表」页面，可以点击展开用户详情弹窗：

xxxxxxxxxx
17
1
function UsersPage() {
2
  // server state: 从后端获取的用户列表
3
  const { data: users } = useQuery({
4
    queryKey: ['users'],
5
    queryFn: getUsers,
6
  });
7
​
8
  // client state: 控制弹窗开关
9
  const [selectedUser, setSelectedUser] = useState<User | null>(null);
10
​
11
  return (
12
    <>
13
      <UserTable users={users} onSelect={setSelectedUser} />
14
      {selectedUser && <UserModal user={selectedUser} onClose={() => setSelectedUser(null)} />}
15
    </>
16
  );
17
}

🔹 users → Server State（后端控制） 🔹 selectedUser → Client State（前端控制）

---

💡 六、结论总结

概念	定义	管理方式	常用库
Client State	UI 内部、用户交互、表单状态	useState / Context / Redux / Zustand	React 内置
Server State	由后端维护，通过 API 获取的数据	React Query / SWR / Apollo	TanStack Query

✅ React 负责渲染 UI ✅ Client State 控制交互逻辑 ✅ Server State 控制数据同步

课程内容如下，还是蛮丰富的：

2 - Project Setup

创建项目，如果不想创建项目，老师的github里面提供了react-query-starter的文件夹，可以直接使用。

1、创建：npm create vite@lastest react-query-demo。

2、使用json-server来创建接口，在项目根目录创建db.json文件，从老师的文件把数据拷贝过来。然后创建脚本命令，以后运行npm run json-server就可以启动服务端了。

3、安装react路由npm i react-router，在main.tsx里面添加路由。

创建三个简单的组件/src/components/Home.tsx、src\components\RQSuperHeroes.tsx、src\components\SuperHeroes.tsx，里面写最简单的代码即可。

然后在App.tsx里面编写路由。

xxxxxxxxxx
35
1
// App.tsx
2
​
3
import { Routes, Route, Link } from "react-router";
4
import "./App.css";
5
import { Home } from "./components/Home";
6
import { SuperHeroes } from "./components/SuperHeroes";
7
import { RQSuperHeroes } from "./components/RQSuperHeroes";
8
​
9
function App() {
10
  return (
11
    <div>
12
      <nav>
13
        <ul>
14
          <li>
15
            <Link to="/">Home</Link>
16
          </li>
17
          <li>
18
            <Link to="super-heroes">Tranditional Super Heroes</Link>
19
          </li>
20
          <li>
21
            <Link to="/rq-super-heroes">RQ Super Heroes</Link>
22
          </li>
23
        </ul>
24
      </nav>
25
​
26
      <Routes>
27
        <Route path="/super-heroes" element={<SuperHeroes />} />
28
        <Route path="/rq-super-heroes" element={<RQSuperHeroes />} />
29
        <Route path="/" element={<Home />} />
30
      </Routes>
31
    </div>
32
  );
33
}
34
​
35
export default App;

然后按照老师的样式修改App.css和index.css就行了。运行项目：

来看一下使用useState和useEffect来获取数据是什么样的：

安装axios，npm i axios。

xxxxxxxxxx
32
1
// src\components\SuperHeroes.tsx
2
​
3
import axios from "axios";
4
import { useEffect, useState } from "react";
5
​
6
export const SuperHeroes = () => {
7
  const [isLoading, setIsLoading] = useState(true);
8
  const [data, setData] = useState<{ name: string }[]>([]);
9
​
10
  useEffect(() => {
11
    // 这里本来可以直接请求数据的，但是加了一个异步请求延时来演示一下。
12
    async function getData() {
13
      await new Promise((resolve) => setTimeout(resolve, 1000));
14
      axios.get("http://localhost:4000/superheroes").then((res) => {
15
        setData(res.data);
16
        setIsLoading(false);
17
      });
18
    }
19
​
20
    getData();
21
  }, []);
22
​
23
  if (isLoading) return <h2>Loading...</h2>;
24
  return (
25
    <>
26
      <h2>Super Heroes Page</h2>
27
      {data.map((hero) => (
28
        <div key={hero.name}>{hero.name}</div>
29
      ))}
30
    </>
31
  );
32
};

3 - Fetching Data with useQuery

react-query在2022年停止更新了，文档推荐使用@tanstack/react-query。

安装依赖：npm i @tanstack/react-query。

没想到技术更新这么快，我看一下能不能按照老师的课程标题来使用这个新的库学习，先做着吧。

1、引入Provider，创建client，为应用提供client

xxxxxxxxxx
21
1
// App.tsx
2
​
3
......
4
​
5
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
6
​
7
// 创建client
8
const queryClient = new QueryClient();
9
​
10
function App() {
11
  return (
12
    // 为应用提供client
13
    <QueryClientProvider client={queryClient}>
14
      <div>
15
        ......
16
      </div>
17
    </QueryClientProvider>
18
  );
19
}
20
​
21
export default App;

2、使用useQuery来获取数据

xxxxxxxxxx
29
1
// src\components\RQSuperHeroes.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
export const RQSuperHeroes = () => {
7
  // useQuery 的返回值有很多，这里使用最简单的isLoading和data
8
  const { isLoading, data } = useQuery<{ name: string }[]>({
9
    // 需要提供queryKey，必须是唯一值。这个key可以用来重新请求数据、缓存、共享请求。
10
    queryKey: ["super-heroes"],
11
    // queryFn就是请求数据的方法
12
    queryFn: async () => {
13
      return await axios.get("http://localhost:4000/superheroes").then((res) => {
14
        return res.data;
15
      });
16
    },
17
  });
18
​
19
  if (isLoading) return <h2>Loading...</h2>;
20
​
21
  return (
22
    <>
23
      <h2>RQSuperHeroes Page</h2>
24
      {data?.map((hero) => (
25
        <div key={hero.name}>{hero.name}</div>
26
      ))}
27
    </>
28
  );
29
};

可以将queryFn抽离出来：

xxxxxxxxxx
29
1
// src\components\RQSuperHeroes.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
// 定义请求数据的函数
7
const fetchSuperHeroes = async (): Promise<{ name: string }[]> => {
8
  const res = await axios.get("http://localhost:4000/superheroes");
9
  return res.data;
10
};
11
​
12
export const RQSuperHeroes = () => {
13
  const { isLoading, data } = useQuery<{ name: string }[]>({
14
    queryKey: ["super-heroes"],
15
    // queryFn的值就是一个函数
16
    queryFn: fetchSuperHeroes,
17
  });
18
​
19
  if (isLoading) return <h2>Loading...</h2>;
20
​
21
  return (
22
    <>
23
      <h2>RQSuperHeroes Page</h2>
24
      {data?.map((hero) => (
25
        <div key={hero.name}>{hero.name}</div>
26
      ))}
27
    </>
28
  );
29
};

4 - Handling Query Error

传统处理错误的方式

定义error状态，然后在请求数据的时候catch，如果有error就展示。

效果：

useQuery中处理错误的方式

useQuery的返回值有error和isError，可以使用它们来处理错误。

5 - React Query Devtools

安装npm i @tanstack/react-query-devtools。

在App.tsx中引入并使用。

xxxxxxxxxx
21
1
// App.tsx
2
​
3
......
4
​
5
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
6
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
7
​
8
const queryClient = new QueryClient();
9
​
10
function App() {
11
  return (
12
    <QueryClientProvider client={queryClient}>
13
      ......
14
          
15
      {/* initialOpen设置是否默认打开，buttonPosition设置打开按钮的位置，默认是bottom-right */}
16
      <ReactQueryDevtools initialIsOpen={false} buttonPosition="bottom-right" />
17
    </QueryClientProvider>
18
  );
19
}
20
​
21
export default App;

可以看到，在页面的右下角，出现了一个button，打开可以看到发起的请求信息。后面会详细介绍这个工具的使用方法。

6 - Query Cache

使用ctrl+shift+r，清除缓存重新加载，然后查看传统请求和useQuery的区别。

我在两个接口请求时，都添加了延时，可以看到传统方式一直显示loading，而useQuery在第一次显示loading之后，就不再显示了，这就是cache缓存的作用。

原理是这样的：当某个queryKey的请求触发之后，isLoading被设置为true，网络请求被发起。当网络请求完成后，react-query会根据queryKey和queryFn将请求结果缓存下来，当重新触发这个请求时，react-query会检查是否存在符合queryKey和queryFn缓存的数据，如果存在，缓存数据会被返回，此时的isLoading不会变为true。react-query知道数据可能会有变化，缓存的数据可能不是最新的，所以在background会触发这个请求，当请求成功后，会在UI上渲染最新的数据。

因为我们的数据没有变化，所以没有看到UI的变化。那有没有东西可以证明background的重新请求发生了呢？有，useQuery返回一个isFetching，可以帮助我们理解。

可以看到，当第一次请求时，isLoading是正常工作的，先是true，请求成功之后变为false。isFetching也是一样。

接下来我们把db.json里面的数据改一下，重新访问这个页面，看一下效果：

可以看到，使用了缓存的数据，数据请求成功之后会更新UI。isLoading一直是false。isFetching先是true，后是false。

react-query缓存的时间默认是300000ms，也就是5分钟。如果想要修改缓存时间，可以向useQuery传入参数gcTime，时间单位是ms。

xxxxxxxxxx
6
1
const { isLoading, data, error, isError, isFetching } = useQuery<{ name: string }[], Error>({
2
    queryKey: ["super-heroes"],
3
    queryFn: fetchSuperHeroes,
4
    // 垃圾回收时间
5
    gcTime: 5000,
6
});

比如说我们设置gcTime: 5000，缓存时间改为5s，看一下效果：

可以看到，5s后这个请求缓存会被垃圾回收处理。

这种缓存做的很好，只在第一次触发loading的显示，后面都是在后台默默的刷新，只要接口返回数据快，我感觉显示效果很好。

7 - Stale Time

stale time：陈旧时间。在数据缓存和Web 开发中非常重要的概念，，它用来定义数据在被认为是“新鲜”的时长。决定了你的应用在多长时间内会信任缓存中的数据，而不会尝试去重新获取新数据。

如果用户可以在一段时间内看缓存的数据，那么我们就没有必要在后台重新请求数据。这时候可以为useQuery设置staleTime参数，设置多长时间内不重新请求数据，单位是ms，默认值为0。

xxxxxxxxxx
6
1
const { isLoading, data, error, isError, isFetching } = useQuery<{ name: string }[], Error>({
2
    queryKey: ["super-heroes"],
3
    queryFn: fetchSuperHeroes,
4
    // 保持新鲜的时长
5
    staleTime: 30000,
6
});

可以看到，第一次请求数据时，network里面有显示，但第二次就没有了，说明在stale time内，不会发起请求。

8 - Refetch Defaults

这节课再来看一些refetch相关的默认设置。

refetchOnMount

作用是控制当一个组件“挂载”（Mount）时，是否应该重新触发一次数据请求。默认是true。

组件“挂载”通常发生在：

1. 组件第一次被渲染到屏幕上时。
2. 用户离开一个页面，然后又返回到这个页面时（导致组件被卸载后又重新挂载）。

它的值有true | false | "always"，当设置为always时，当组件挂载时，总是重新获取数据。它会无视 staleTime。不管数据是不是“新鲜”的 (fresh)，只要组件一挂载，就立刻强制发起一次新的网络请求。

refetchOnWindowFocus

作用：当浏览器窗口或标签页重新获得焦点（Focus）时，检查并重新获取已挂载查询的数据。

值有true | false | "always"。当设置为always时，强制重新获取窗口聚焦时，无视 staleTime，总是触发重新获取。

场景举例

想象一个用户正在使用你的应用，然后在后台打开了一个新的标签页，或者切换到了另一个程序，几分钟后用户又：

1. 点击 了你的浏览器标签页。
2. Alt + Tab 切换回了你的应用程序窗口。
3. 点击 了页面上的空白区域使页面重新聚焦。

一旦发生上述操作，如果设置了 refetchOnWindowFocus，React Query 就会在后台自动触发一次数据请求，将当前页面上的旧数据更新为最新数据。

看一下传统数据请求在用户切换窗口之后，会不会重新请求数据。我先打开Traditional Super Heroes页面，然后在db.json里面修改数据，看会不会重新获取数据。

可以看到，没有。

react query里面的表现，可以看到重新请求了数据。

9 - Polling

Polling (轮询) 是一种非常基础且常见的网络通信技术，用于在客户端（如浏览器、App）和服务器之间同步数据或检查状态。轮询就是客户端每隔固定的时间间隔，主动向服务器发送请求，询问“是否有新数据或新状态？”。

比如说我展示一个股票的界面，需要隔一段时间显示最新的数据，这时候的需求就是不断请求数据。

那在react query里面怎么做到呢？可以设置refetchInterval参数，默认是false，如果设置为数字，单位为ms。

xxxxxxxxxx
6
1
const { isLoading, data, error, isError, isFetching } = useQuery<{ name: string }[], Error>({
2
    queryKey: ["super-heroes"],
3
    queryFn: fetchSuperHeroes,
4
    // 设置重新请求的时间间隔
5
    refetchInterval: 2000,
6
});

可以看到，每隔2s，会重新请求数据。

当浏览器没有focus的时候，即使设置了refetchInterval，请求也会中断。如果想在浏览器没有focus的时候，依然请求数据，这时候可以设置refetchIntervalInBackground: true。

题外话

除了轮询，还有什么技术？

技术	方式	实时性	典型场景
Polling (轮询)	客户端主动问：“好了吗？” (每 N 秒问一次)	低	简单的状态检查，或低实时性要求。
Long Polling (长轮询)	客户端问：“好了吗？” 服务器先不回，直到有数据或超时才回。	中高	在 WebSocket 不支持时的替代方案。
WebSockets	双向持久连接，服务器随时可以推送数据。	极高 (实时)	实时聊天、多人游戏、股票行情。
Server-Sent Events (SSE)	单向持久连接，服务器可以主动向客户端推送数据。	高	新闻推送、实时更新的仪表盘。

10 - useQuery on click

之前触发网络请求，要么是组件onMount时、要么是window focus时。如果我想在点击某个元素的时候触发网络请求，怎么做呢？

1、设置useQuery不要再组件onMount时请求数据，使用enabled参数

xxxxxxxxxx
6
1
const { isLoading, data, error, isError, isFetching } = useQuery<{ name: string }[], Error>({
2
    queryKey: ["super-heroes"],
3
    queryFn: fetchSuperHeroes,
4
    // 设置不要在组件onMount的时候发起网络请求
5
    enabled: false,
6
  });

2、使用useQuery的返回值refetch，可以手动触发网络请求

xxxxxxxxxx
37
1
// components\RQSuperHeroes.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
const fetchSuperHeroes = async (): Promise<{ name: string }[]> => {
7
  await new Promise((resolve) => setTimeout(resolve, 1000));
8
  const res = await axios.get("http://localhost:4000/superheroes");
9
  return res.data;
10
};
11
​
12
export const RQSuperHeroes = () => {
13
  // 解构出 refetch 方法
14
  const { isLoading, data, error, isError, isFetching, refetch } = useQuery<{ name: string }[], Error>({
15
    queryKey: ["super-heroes"],
16
    queryFn: fetchSuperHeroes,
17
      // 设置不要在组件onMount的时候发起网络请求
18
    enabled: false,
19
  });
20
​
21
  console.log({ isLoading, isFetching });
22
​
23
  if (isLoading) return <h2>Loading...</h2>;
24
​
25
  if (isError) return <h2>{error.message}</h2>;
26
​
27
  return (
28
    <>
29
      <h2>RQSuperHeroes Page</h2>
30
      {/* 设置手动触发网络请求 */}
31
      <button onClick={() => refetch()}>Fetch Heroes</button>
32
      {data?.map((hero) => (
33
        <div key={hero.name}>{hero.name}</div>
34
      ))}
35
    </>
36
  );
37
};

可以看到，手动触发之后才发起请求。并且staleTime和cache也是同样工作的。

如果想在再次手动触发的时候显示loading效果，可以使用isFetching来帮忙。

xxxxxxxxxx
1
1
if (isLoading || isFetching) return <h2>Loading...</h2>;

11 - Success and Error Callbacks

在数据请求之后，我们可能想做一些副作用，比如说打开一个modal、跳转到一个新路由、或者显示toast提示信息。

原来的做法：

但是在@tanstack/react-queryv5里面的useQuery里面的onSuccess和onError已经移除了，但在useMutation里面还保留着。

因为这些回调不会在数据从缓存中直接读取时触发。比如数据被缓存后，再次同 key 请求可能直接走缓存，不会触发 onSuccess。

那这里该怎么写呢？我觉得onSuccess可以直接使用isSuccess来代替，而onError可以用isError和error来代替，结合useEffect来使用。

xxxxxxxxxx
41
1
import { useQuery } from "@tanstack/react-query";
2
import axios from "axios";
3
import { useEffect } from "react";
4
​
5
const fetchSuperHeroes = async (): Promise<{ name: string }[]> => {
6
  await new Promise((resolve) => setTimeout(resolve, 1000));
7
  const res = await axios.get("http://localhost:4000/superheroes");
8
  return res.data;
9
};
10
​
11
export const RQSuperHeroes = () => {
12
  // 解构出 isSuccess isError error
13
  const { isLoading, data, error, isError, isFetching, isSuccess } = useQuery<{ name: string }[], Error>({
14
    queryKey: ["super-heroes"],
15
    queryFn: fetchSuperHeroes,
16
  });
17
​
18
​
19
  useEffect(() => {
20
    if (isSuccess) {
21
      console.log("Perform side effect after data fetching");
22
    }
23
    if (isError) {
24
      console.log("Perform side effct after encountering error", error.message);
25
    }
26
  }, [isSuccess, isError, error]);
27
​
28
    
29
  if (isLoading || isFetching) return <h2>Loading...</h2>;
30
​
31
  if (isError) return <h2>{error.message}</h2>;
32
​
33
  return (
34
    <>
35
      <h2>RQSuperHeroes Page</h2>
36
      {data?.map((hero) => (
37
        <div key={hero.name}>{hero.name}</div>
38
      ))}
39
    </>
40
  );
41
};

先看请求成功，然后修改请求地址看请求失败的情况：

可以看到，请求失败之后，会重试3次，3次再失败才会变更isError的值。

12 - Data Transformation

这节课学习转变接口返回数据的格式。

可以使用useQuery的select参数，传递一个函数进去，这个函数可以接收到接口返回的数据。这时候useQuery的ts类型，需要传递第3个泛型进去。

假设需求是：将superheroes的返回结果改为字符串数组，这样就不需要使用hero.name来访问了。

xxxxxxxxxx
34
1
// RQSuperHeroes.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
import { useEffect } from "react";
6
​
7
const fetchSuperHeroes = async (): Promise<{ name: string }[]> => {
8
  await new Promise((resolve) => setTimeout(resolve, 1000));
9
  const res = await axios.get("http://localhost:4000/superheroes1");
10
  return res.data;
11
};
12
​
13
export const RQSuperHeroes = () => {
14
  // useQuery 的ts类型，要传递第三个泛型参数进去，这表示select之后返回结果的类型
15
  const { isLoading, data, error, isError, isFetching, isSuccess } = useQuery<{ name: string }[], Error, string[]>({
16
    queryKey: ["super-heroes"],
17
    queryFn: fetchSuperHeroes,
18
    // select参数的值是一个函数，函数可以接收到接口返回的数据，然后做处理即可
19
    select: (data) => {
20
      return data.map((hero) => hero.name);
21
    },
22
  });
23
​
24
  ......
25
​
26
  return (
27
    <>
28
      <h2>RQSuperHeroes Page HeroNames</h2>
29
      {data?.map((heroName) => (
30
        <div key={heroName}>{heroName}</div>
31
      ))}
32
    </>
33
  );
34
};

13 - Custom Query Hook

这节课学习怎么包裹useQuery这个hook，创建自定义的hook，这样在不同的组件里面，我们就可以使用自定义hook来调用接口了。

1、创建hook

因为hook就是一个函数，我们要的最终返回结果是什么呢？其实就是useQuery的调用过程，这一点是最重要的，要搞清楚。

xxxxxxxxxx
22
1
// src\hooks\useSuperHeroesData.ts
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
const fetchSuperHeroes = async (): Promise<{ name: string }[]> => {
7
  await new Promise((resolve) => setTimeout(resolve, 1000));
8
  const res = await axios.get("http://localhost:4000/superheroes");
9
  return res.data;
10
};
11
​
12
export const useSuperHeroesData = () => {
13
  return useQuery<{ name: string }[], Error, string[]>({
14
    // 需要提供queryKey，必须是唯一值。这个key可以用来重新请求数据、缓存、共享请求。
15
    queryKey: ["super-heroes"],
16
    // queryFn就是请求数据的方法
17
    queryFn: fetchSuperHeroes,
18
    select: (data) => {
19
      return data.map((hero) => hero.name);
20
    },
21
  });
22
}

注意：自定义hook中可以设置参数，然后用到useQuery里面就行了。这就是函数柯里化。

2、然后在不同的组件里面使用自定义hook即可

xxxxxxxxxx
31
1
// src\components\RQSuperHeroes.tsx
2
​
3
import { useEffect } from "react";
4
import { useSuperHeroesData } from "../hooks/useSuperHeroesData";
5
​
6
export const RQSuperHeroes = () => {
7
  // 只需要调用 useSuperHeroesData 即可
8
  const { isLoading, data, error, isError, isFetching, isSuccess } = useSuperHeroesData();
9
​
10
  useEffect(() => {
11
    if (isSuccess) {
12
      console.log("Perform side effect after data fetching");
13
    }
14
    if (isError) {
15
      console.log("Perform side effct after encountering error", error.message);
16
    }
17
  }, [isSuccess, isError, error]);
18
​
19
  if (isLoading || isFetching) return <h2>Loading...</h2>;
20
​
21
  if (isError) return <h2>{error.message}</h2>;
22
​
23
  return (
24
    <>
25
      <h2>RQSuperHeroes Page HeroNames</h2>
26
      {data?.map((heroName) => (
27
        <div key={heroName}>{heroName}</div>
28
      ))}
29
    </>
30
  );
31
};

工作正常：

14 - Query by Id

这节课学习怎么使用id来查询详情数据。需要做下面的事情：

1、创建RQSuperHeroDetail.tsx文件

xxxxxxxxxx
5
1
// src\components\RQSuperHeroDetail.tsx
2
​
3
export const RQSuperHeroDetail = () => {
4
  return <div>RQSuperHeroDetail</div>;
5
};

2、在App.tsx里面添加路由，在RQSuperHeroes页面添加跳转链接

xxxxxxxxxx
7
1
// src\components\RQSuperHeroes.tsx
2
​
3
{data?.map((hero) => (
4
    <div key={hero.id}>
5
        <Link to={`/rq-super-heroes/${hero.id}`}>{hero.name}</Link>
6
    </div>
7
))}

可以看到，跳转正常：

3、编写自定义hook，获取详情数据

xxxxxxxxxx
25
1
// src\hooks\useSuperHeroDetail.ts
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
type User = {
7
  name: string;
8
  id: number;
9
  alterEgo: string;
10
}
11
​
12
// 接口请求的函数
13
const fetchSuperHero = async (id: string): Promise<User> => {
14
  const res = await axios.get("http://localhost:4000/superheroes/" + id)
15
  return res.data;
16
}
17
​
18
// 自定义Hook
19
export const useSuperHeroDetail = (id: string) => {
20
  return useQuery({
21
    // 这里的queryKey需要多传递一个id，因为id值不同，缓存也不同
22
    queryKey: ["super-hero", id],
23
    queryFn: () => fetchSuperHero(id)
24
  })
25
}

4、在页面中使用自定义hook获取数据

xxxxxxxxxx
19
1
// src\components\RQSuperHeroDetail.tsx
2
​
3
import { useParams } from "react-router";
4
import { useSuperHeroDetail } from "../hooks/useSuperHeroDetail";
5
​
6
export const RQSuperHeroDetail = () => {
7
  // 利用react-router的方法，获取params参数
8
  const { heroId } = useParams();
9
  const { isLoading, data, isError, error } = useSuperHeroDetail(heroId || "");
10
​
11
  if (isLoading) return <h2>Loading...</h2>;
12
  if (isError) return <h2>{error.message}</h2>;
13
​
14
  return (
15
    <div>
16
      {data?.name} - {data?.alterEgo}
17
    </div>
18
  );
19
};

可以看到，获取了详情数据。

注意：在指定queryFn的函数时，可以不传递参数，useQuery会将参数传递过来，里面有一个querykey的参数，是一个数据，获取它的第二个参数即可。

15 - Parallel Queries

有时候，一个组件里面需要调用多个API接口来获取需要的数据，多个接口之间没有相互关系，所以称它们为平行请求。

创建新组件：

xxxxxxxxxx
5
1
// src\components\ParallelQueries.tsx
2
​
3
export const ParallelQueries = () => {
4
  return <div>ParallelQueries</div>;
5
};

App.tsx里面添加新路由<Route path="/rq-parallel" element={<ParallelQueries />} />。

需求就是在新组件里面，请求superheroes和friends的数据。

xxxxxxxxxx
43
1
// src\components\ParallelQueries.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
const fetchSuperHeroes = async (): Promise<{ id: string; name: string; alterEgo: string }[]> => {
7
  const res = await axios.get("http://localhost:4000/superheroes");
8
  return res.data;
9
};
10
​
11
const fetchFriends = async (): Promise<{ id: string; name: string }[]> => {
12
  const res = await axios.get("http://localhost:4000/frieds");
13
  return res.data;
14
};
15
​
16
export const ParallelQueries = () => {
17
  // 只需要写两个useQuery就行了
18
  const { data: superHeroes } = useQuery({
19
    queryKey: ["super-heroes"],
20
    queryFn: fetchSuperHeroes,
21
  });
22
  const { data: friends } = useQuery({
23
    queryKey: ["friends"],
24
    queryFn: fetchFriends,
25
  });
26
  return (
27
    <>
28
      <h2>Super Heroes</h2>
29
      {superHeroes?.map((hero) => (
30
        <div key={hero.id}>
31
          {hero.id} - {hero.name} - {hero.alterEgo}
32
        </div>
33
      ))}
34
​
35
      <h2>Friends</h2>
36
      {friends?.map((f) => (
37
        <div key={f.id}>
38
          {f.id} - {f.name}
39
        </div>
40
      ))}
41
    </>
42
  );
43
};

16 - Dynamic Parallel Queries

动态平行查询。

案例：我DynamicParallel页面，请求多个superhero的详情数据，传递的heroIds的长度是未知的。所以不能像上节课那样，使用多个useQuery来解决问题，而是需要使用useQueries。

添加路由：

xxxxxxxxxx
1
1
<Route path="/rq-dynamic-parallel" element={<DynamicParallel heroIds={[1, 3]} />} />

编写组件：

xxxxxxxxxx
36
1
// src\components\DynamicParallel.tsx
2
​
3
import { useQueries, UseQueryResult } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
const fetchSuperHeroData = async (id: number): Promise<{ id: string; name: string }> => {
7
  const res = await axios.get(`http://localhost:4000/superheroes/${id}`);
8
  return res.data;
9
};
10
​
11
export const DynamicParallel = ({ heroIds }: { heroIds: number[] }) => {
12
  // 使用 useQueries 的queries参数，参数值是数组。这里是了数组的map方法，返回的是数组
13
  const results = useQueries({
14
    queries: heroIds.map((item) => ({
15
      queryKey: ["super-hero", item],
16
      queryFn: () => fetchSuperHeroData(item),
17
    })),
18
  }) as UseQueryResult<{ id: string; name: string }>[];
19
​
20
  if (results.length === 0) return <h2></h2>;
21
​
22
  return (
23
    <div>
24
      {results.map((c) => {
25
        // 只渲染成功的数据
26
        if (!c.data) return null;
27
​
28
        return (
29
          <div key={c.data?.id}>
30
            {c.data?.id} - {c.data?.name}
31
          </div>
32
        );
33
      })}
34
    </div>
35
  );
36
};

可以看到，两个请求发起了。

如果多个请求返回的结果结构类似，还可以使用combine方法，将多个返回结果合并成一个：

实际应用场景：

一个组件中需要同时加载多个接口的数据。比如：

• 用户信息 /api/user/1
• 用户的文章 /api/user/1/posts
• 用户的好友列表 /api/user/1/friends

那么就可以写成这样：

xxxxxxxxxx
7
1
const results = useQueries({
2
  queries: [
3
    { queryKey: ['user', id], queryFn: fetchUser },
4
    { queryKey: ['posts', id], queryFn: fetchPosts },
5
    { queryKey: ['friends', id], queryFn: fetchFriends },
6
  ],
7
})

results 是一个数组：

xxxxxxxxxx
5
1
[
2
  { data, isLoading, error, ... },  // user
3
  { data, isLoading, error, ... },  // posts
4
  { data, isLoading, error, ... }   // friends
5
]

17 - Dependent Queries

有时候，我们需要按照顺序请求数据，下一个请求的参数要依靠上一个请求的返回结果。

在db.json里面新增数据：

需求：先根据email获取user信息，然后根据channelId获取courses信息。

1、添加路由：

xxxxxxxxxx
1
1
<Route path="/rq-dependent" element={<DependentQueries email="vishwas@example.com" />} />

2、获取数据

xxxxxxxxxx
38
1
// src\components\DependentQueries.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
const fetchUserByEmail = async (email: string): Promise<{ channelId: string }> => {
7
  const res = await axios.get(`http://localhost:4000/users/${email}`);
8
  return res.data;
9
};
10
​
11
const fetchCoursesByChannelId = async (channelId: string): Promise<string[]> => {
12
  const res = await axios.get(`http://localhost:4000/channels/${channelId}`);
13
  return res.data;
14
};
15
​
16
export const DependentQueries = ({ email }: { email: string }) => {
17
  const { data: user } = useQuery({
18
    queryKey: ["user", email],
19
    queryFn: () => fetchUserByEmail(email),
20
  });
21
​
22
  const channelId = user?.channelId || "";
23
​
24
  const { data: courses } = useQuery({
25
    queryKey: ["courses", channelId],
26
    queryFn: () => fetchCoursesByChannelId(channelId),
27
    // enabled: !!channelId 是核心，它会让查询完全不发起，直到条件满足。
28
    enabled: !!channelId,
29
  });
30
​
31
  return (
32
    <div>
33
      {courses?.map((c) => (
34
        <div key={c}>{c}</div>
35
      ))}
36
    </div>
37
  );
38
};

还是使用两个useQuery，核心是：在第二个请求中，设置enabled: !!channelId，这样当channelId没有值时，第二个请求是不会发起的。

这两个接口的执行流程到底是什么呢？

执行流程全过程（从组件 mount 开始，每一毫秒都说清楚，下面的时间ms都是模拟说明的文字）

你只管写 enabled: !!dep，React Query 帮你处理了“创建/销毁/订阅/缓存/重试”所有脏活！

每个 useQuery 钩子 = React Query 在内部 new QueryObserver() 一个实例，它负责：

• 监听缓存（data 更新就 rerender）
• 执行 fetch（网络请求）
• 管理状态（loading / error / idle）
• 垃圾回收（组件卸载时自动销毁）

18 - Initial Query Data

这节课学习怎么为query请求提供初始的查询数据，当从superheroes列表访问详情的时候，我们可以使用列表里面的一些数据，提供给详情界面先显示，然后里面请求更具体的详情数据。

1、使用queryClient的getQueryData方法，拿到列表的数据

2、使用拿到的数据，设置useQuery的initialData的值

xxxxxxxxxx
32
1
// src\hooks\useSuperHeroDetail.ts
2
​
3
import { useQuery, useQueryClient } from "@tanstack/react-query";
4
import axios from "axios";
5
​
6
type User = {
7
  name: string;
8
  id: string;
9
  alterEgo: string;
10
}
11
​
12
// 接口请求的函数
13
const fetchSuperHero = async ({ queryKey }: { queryKey: [string, string] }): Promise<User> => {
14
  const [, id] = queryKey;
15
  const res = await axios.get("http://localhost:4000/superheroes/" + id)
16
  return res.data;
17
}
18
​
19
// 自定义Hook
20
export const useSuperHeroDetail = (id: string) => {
21
  const queryClient = useQueryClient();
22
  return useQuery({
23
    queryKey: ["super-hero", id],
24
    queryFn: fetchSuperHero,
25
    // 使用initialData赋初始值，然后使用queryClien获取列表数据
26
    initialData: () => {
27
      const heroes = queryClient.getQueryData<User[]>(["super-heroes"]);
28
      const hero = heroes?.find(hero => hero.id === id);
29
      return hero ?? undefined;
30
    }
31
  })
32
}

可以看到，数据显示了，但是network里面过了一段时间才发起请求，说明初始值成功赋值。

19 - Paginated Queries

这节课学习分页请求。

1、添加路由：

xxxxxxxxxx
1
1
<Route path="/rq-paginated" element={<PaginatedQueriesPage />} />

2、编写组件

json server的分页这样写：http://localhost:4000/colors?_page=2&_per_page=2。

思路是创建一个页码的状态，把这个状态传递给请求数据的函数。当这个状态变化时，组件会重新渲染，那么useQuery会接收到最新的页码来请求数据。流程并不复杂。

xxxxxxxxxx
47
1
// src\components\PaginatedQueries.tsx
2
​
3
import { useQuery } from "@tanstack/react-query";
4
import axios from "axios";
5
import { useState } from "react";
6
​
7
const fetchColors = async (
8
  pageNum: number
9
): Promise<{
10
  data: { id: string; label: string }[];
11
}> => {
12
  const res = await axios.get(`http://localhost:4000/colors?_page=${pageNum}&_per_page=2`);
13
  return res.data;
14
};
15
​
16
export const PaginatedQueriesPage = () => {
17
  const [pageNumber, setPageNumber] = useState(1);
18
  const { isLoading, isError, error, data } = useQuery({
19
    queryKey: ["colors", pageNumber],
20
    queryFn: () => fetchColors(pageNumber),
21
  });
22
​
23
  if (isLoading) return <h2>Loading...</h2>;
24
  if (isError) return <h2>{error.message}</h2>;
25
​
26
  return (
27
    <>
28
      <div>
29
        {data?.data?.map((color) => (
30
          <div key={color.id}>
31
            <h2>
32
              {color.id}. {color.label}
33
            </h2>
34
          </div>
35
        ))}
36
      </div>
37
      <div>
38
        <button onClick={() => setPageNumber((page) => page - 1)} disabled={pageNumber === 1}>
39
          Prev Page
40
        </button>
41
        <button onClick={() => setPageNumber((page) => page + 1)} disabled={pageNumber === 4}>
42
          Next Page
43
        </button>
44
      </div>
45
    </>
46
  );
47
};

可以看到，分页效果很好。

但是有个问题，就是每次请求新数据的时候，都有Loading，能不能不显示loading，而是显示之前的数据，可以使用placeholderData属性。（我觉得显示loading才是正常的，显示之前的数据可能让用户觉得点击按钮不起作用，会一直点击）

xxxxxxxxxx
5
1
const { isLoading, isError, error, data } = useQuery({
2
    queryKey: ["colors", pageNumber],
3
    queryFn: () => fetchColors(pageNumber),
4
    placeholderData: (previousData) => previousData,
5
});